Introduction

The 8.5.1 release of Notes/Domino sees the arrival of XPages to the Notes client platform, having made its public debut on the Domino server earlier in 2009 when V8.5 went on general release.

XPages in the Notes client (or XPiNC as we may conveniently refer to it later) was a much-demanded feature from the Notes application development community. Its delivers business value by addressing major customer use cases, like enabling XPages web applications for offline use. Other new XPages features, like its support for a standard component model, are promising from a client platform standpoint, insofar as XPages can now fully participate in client composite applications, thus facilitating a whole new variety of interesting scenarios.

For many developers however, there is a more general point of interest waiting to unfold, i.e. how do web technologies behave and adapt when transplanted from a web environment to the client platform. Although XPages is inherently multi-platform in design, its roots are firmly in the web world and the jury is currently out as to how well XPages will work for rich desktop applications. In this regard, many different factors will determine how XPages survives and thrives as part of the Notes client … how well it integrates native client behaviours, how XPages applications interoperate with regular Notes applications, etc. This article examines some mainstream use cases in the general arena of client integration, examining what XPages supports in V8.5.1, and what can be achieved in the future.

Link Handling

It is perhaps simplest to explain and develop these integration points using the standard Notes/Domino discussion application as an example. This app is widely used as a basis for team collaboration, and since the release of V8.5, the out-of-the-box Discussion template ships with a cool XPages Web 2.0 interface

Figure 1 – New XPages Client Launch Property for V8.5.1


Many readers should already be familiar with the workings of this template and can configure it to run in the client using XPages by simply selecting the appropriate launch page. For the Discussion application, just choose the same page that is used for XPages on the web – see Figure 1 above.

A cursory examination of a sample discussion application will usually highlight the pre-dominant usage of links in any document repository. Joe User typically creates simple links to other related documents in the same database, links to views in other databases, links to databases on remote servers and so on. The types of links can be many and varied, although the document, view and database links are by far the most common. So what happens to these links when I use XPages on the client to run a pre-existing discussion application?

The good news is that your XPiNC user experience is very consistent with link handling in the regular client. That is, links are identified and rendered in the XPages application, and a single or double click will open the document, view or database in a new Notes client tab. Figure 2 shows a document containing a collection of such links in a Notes document.

Figure 2 – Links in a standard Notes client discussion application

If the same document is opened while running the application using XPiNC, then Figure 3 shows the equivalent rendering. As you can see, apart from some arbitrary page layout variances and different icon imagery, the content is as you would expect.

Figure 3 – Links Rendered Using XPiNC



The inquisitive reader may of course view the page source using the XPages client tool bar and see how these links are represented internally. Such links may in fact be difficult for us humans to immediately decipher, due to the encoding of reserved HTML characters and verbose view IDs and document IDs, but the general form of a simple Notes document link is as follows:



Once emitted in this form, Notes will handle the link by locating the document and opening it in a tab window. Now, if only it was all just that simple! Links are not saved in this form internally, regardless of whether the rich text container object is stored as MIME or as native CD records. That is, a number of internal transformations must first take place in order for XPages to produce a generic Notes link in the form shown above. Let’s work through a typical use case.

When XPages opens a Notes document that contains one or more rich text objects that are stored internally as CD records (i.e. rich documents created directly in the Notes client), they are first converted from their native binary format to MIME using a set of internal services known as HAPI. I am no longer sure as to the provenance of this acronym, but suffice to say that HAPI is a private internal library of services that can be called upon to perform the CD/MIME conversions.

The rich text object returned to XPages after a HAPI MIME conversion would typically contain Domino document links of the following form:



Once we get beyond the fog factor created by the view universal ID and the document universal ID, the URL is fairly straightforward, i.e. basically a standard Domino ?OpenDocument URL, displayed with a clickable image. When running on the web, XPages has no further work to perform once this initial MIME conversion is completed – hurray! This is because there is sufficient information in the URL for the Domino web server to resolve the document and serve it up to the browser should the user click the image link. Moreover, XPages does not in fact process this resource request at all … it handled totally by the classic Domino HTTP server.

This same converted link is not a whole lot of use to XPages when running on the client platform. Firstly, there is no Domino HTTP server running on the client to pre-process the URL for XPages. Secondly, the expected link behaviour differs insofar as the current page should not be replaced with the contents of the new document (as is the case on the web), but the new document should be opened in a new tab, leaving the current page in its original tabbed window. Basically, there are some extra hoops to jump through in order to transform the Domino link to a Notes link of the form shown initially. So with a little extra parsing, the client URL is generated as follows:



The steps are reasonably straightforward and can be summarized as follows:
1. Prepend the Notes URL protocol, including server name if needed, to the href
2. Add a marker to ensure that this URL is not saved back to the Notes document
3. Substitute the src attribute to a value the XPages resource servlet can resolve

The 2^nd step is interesting because one should note that this Notes client URL transformation is done solely in-memory and not persisted to the document store. The presence of the temporary marker (&XSP_TMP_MARKER) allows XPages to undo this transformation in the event that the document is edited and saved. Other side effects to do with saving converted documents however are discussed in more detail a little later on in this article, under the heading of Document Interoperability.

Before departing the subject of links I should mention another use case that XPages is required to handle on the client. This involves redirect URLs and can occur quite frequently. A redirect URL occurs in the underlying MIME object if the document being processed by XPiNC contains a link to a database that cannot be found in the Notes client workspace. Its format is quite different to those we have seen so far. An example is as follows:



The encodings of reserved characters have not been decoded above in this case. XPiNC must correctly identify and parse the required parts of the redirect URL, in the following manner

Figure 4: Anatomy of a Redirect URL

Part	Parameter	Value
Action	To	?Open
Database	Id	8525753E0078C555
Server	Name	CN=luckyduck/O=IBM

Any previously mentioned substitutions are still required. This allows us to rebuild a client URL with the correct parts re-jigged appropriately (again, not decoded).



The XPages Client URL

All this talk of URLs segues me neatly into this next topic! As we have seen thus far, there is a slew of Notes/Domino URLs out there, designed for performing various actions in the client or on the server. Anything from opening a frameset to sorting a view can performed via Notes/Domino URLs or one type or another. In V8.5.1, the client introduces a new XPages URL. Its form is as follows:

The XPages URL is already in wide use throughout the Notes client, although this may not always be evident to the end-user. For example, an XPages client URL is built dynamically when an XPages application is invoked, based on the client launch properties specified via Domino Designer or directly in the client applications infobox properties shown earlier.

As indicated above, the URL can contain an optional server name, and note also that the database replica id can be used instead of the database name. The replica id is definitely a better choice if you are building an NTF template that others will use to create NSF application instances. Using the replica id ensures that the application creator does not have to change the launch option after creating a new database from the template. For this reason, it is the option used in the Composite Application Editor when adding XPages components. When XPages participates in a composite application, an XPages client URL is generated for each XPages component included in the aggregation. Apart from using the replica id, the XSP page reference part is typically replaced with a component reference, e.g.



The component element itself will define what XPage should be used to display the component at runtime, and the XPages client container automatically extracts this information on your behalf when invoked.

XPages client URLs are used when bookmarking XPages applications (yes, XPages supports client bookmarks), and can also be entered directly into the Notes URL address toolbar to invoke an application on the fly. Figure 5 shows this in action.

Figure 5: Interactively Loading an XPages Client Application



Furthermore the XPages URL can be used to launch XPages applications from other Notes applications. One way to achieve this is simply to include the URL in an @Command and then apply this formula to a Button or Action in a Form, e.g.



Finally, it is best practice to use the ?OpenXPage parameter, but it’s not always strictly required.

Document Interoperability

Any discussion documents created via XPages on the web will most likely contain rich text. Such content is saved in what’s known as MIME format. This Multipurpose Internet Mail Extension format is a standard that’s been around for a while and supports all the fancy stuff we humans like to use when expressing our thoughts in writing – e.g. different fonts, inline graphics, tables, attachments etc.

The Notes client however, supported all this same fancy content before the popular rise of the internet and subsequent creation of the MIME standard. Such content was, and still is, saved in a native rich format known as CD records, where CD stands for composite or compound data.

Wherever two separate formats exist for saving the same data, inconsistencies or data conflicts are inevitable. Remember, for example, that the MIME standard was originally invented so e-mail content could move beyond plain-text communication. MIME represents a system for handling the set of extended objects that can be encapsulated in a HTML page. Many Notes rich objects can be mapped map directly to HTML elements and vice-versa, e.g. buttons, images etc. But there are other rich Notes object that don’t really exist in a MIME world, “Sections” being my favourite example. So a potential problem exists when such CD records need to be saved as MIME items. Going back and forth between formats, or round-tripping documents as it is sometimes known, can be lossy depending on the precise nature of the original content.

MIME/CD round-tripping can occur for a variety of reasons. If, for instance, an application has been built to run on both client and web, then rich documents created on one platform and then later edited and saved on the other force a MIME/CD conversion to take place. Similarly, a Notes e-mail containing rich content sent to an internet addressee can present similar issues once a response is returned to the sender. Up to now, XPages applications have run only on the web. If you have ever edited and saved a rich text document originating from the Notes client in an XPages web application, then you should be familiar with this warning dialog:

Figure 6: User Dialog To Accept Or Reject A CD/MIME Conversion


This is where users come face to face MIME/CD data interoperability. Essentially the dialog is saying that the document may not look the same next time it’s opened in the client. As I said earlier, whether it does or does not very much depends on the particular set of items it contains and their respective MIME/CD compatibility level.

However, what may be a little less intuitive to users of Notes V8.5.1 is why the same dialog can be presented when running an XPages application on the client. After all, the application is running in the client, not the web, so what’s the issue?

The answer is that XPages saves the contents of rich text fields as MIME objects regardless of whether the application is running on the web or the client. If the rich content was created using the native client, then editing and saving the document using XPiNC will cause the data to be rewritten in MIME format. The result is identical to what would happen if the document was saved on the web – leaving XPages out of the loop entirely, i.e. just using the classic Domino web application server.

Although this has been an issue for as long as the Domino web server has existed, perhaps the fact that XPages now runs directly on the Notes client platform means that more users are likely to encounter it for the first time. Circling back to my earlier examples in the Link Handling section, we can see that making an arbitrary change to the document first shown in Figure 2 via the classic Domino web server or XPages will effectively render the links useless if the document is re-opened in the regular client, as shown in Figure 7.

Figure 7 Broken Links


If you are planning to build multi-target applications that run on both the regular client and the web, then you should consider any potential impact of this issue up front. A development initiative is underway to address such interoperability snags for future releases.

Conclusion

It’s easy to get started with XPages for the Notes client in V8.5.1. Apart from enabling you to take your XPages web apps offline, XPages in its own right offers an alternative application development model for the Notes client platform. The first brave steps have been taken in terms of tighter client integration, and users can expect continued improvements as work continues in this area over the coming releases. As usual, your feedback is essential in order to ensure the optimal delivery of features and fixes, so please continue to engage with us as to build the best product for the future.